.\" $Id: estats_log_open_write.3,v 1.1 2003/01/06 20:50:34 engelhar Exp $
.TH ESTATS_LOG 3 "27 JUNE 2002" "Estats Userland" "Estats"
.SH NAME
estats_log_open_write, estats_log_open_read, estats_log_write,
estats_log_close_write, estats_log_close_read,
estats_snap_from_log, estats_snapshot_alloc_from_log
\- read/write the values of Estats variables from/to a file
.SH SYNOPSIS
.B #include <estats/estats.h>
.PP
.nf
.BI "estats_log* estats_log_open_write(char* " logname ", estats_connection* " conn ", estats_group* " group ");"
.BI "estats_log* estats_log_open_read(char* " logname ");"
.BI "int estats_log_write(estats_log* " log ", estats_snapshot* " snap ");"
.BI "int estats_log_close_write(estats_log* " log ");"
.BI "int estats_log_close_read(estats_log* " log "); " 
.BI "int estats_snap_from_log(estats_snapshot* " snap ", estats_log* " log ");
.BI "estats_snapshot* estats_snapshot_alloc_from_log(estats_log* " log ");"
.fi
.SH DESCRIPTION
The values of Estats variables are read atomically from the kernel
on a per connection, per
\fIgroup\fR basis; these atomic snapshots may be written to a file, and later
recovered using the \fIestats_log\fR functions. Snapshots are written to a file
using \fBestats_log_write\fR. The manner of reading snapshots
from a log file mirrors that of reading live data, as follows: to read live
data, one first calls \fBestats_snapshot_alloc\fR, and obtains an atomic
snapshot with \fBestats_snap\fR; to read logged data, one first calls
\fBestats_snapshot_alloc_from_log\fR, and then obtains the logged snapshot with
\fBestats_snap_from_log\fR. \fIestats_log\fR file handling is done through the
appropriate open and close functions.
.PP
\fBestats_log_open_write\fR opens a \fIestats_log\fR file for writing live
data.
\fBestats_log_open_read\fR opens a estats_log file for reading logged data.
.PP
\fBestats_log_write\fR writes a snapshot to a writable \fIestats_log\fR file.
.PP
\fBestats_log_close_write\fR closes a writable \fIestats_log\fR file.
\fBestats_log_close_read\fR closes a readable \fIestats_log\fR file.
.PP
\fBestats_snapshot_alloc_from_log\fR allocates a snapshot structure of
sufficient size for reading from a given \fIestats_log\fR file.
\fBestats_snap_from_log\fR reads the next snapshot from the \fIestats_log\fR file.  
.SH RETURN VALUES
\fBestats_log_open_write\fR, respectively, \fBestats_log_open_read\fR return the
writable, resp., readable \fIestats_log\fR file, or NULL upon failure.
.PP
\fBestats_log_write\fR, \fBestats_log_close_write\fR, \fBestats_log_close_read\fR,
and \fBestats_snap_from_log\fR, return 0 upon success, or \fIestats_errno\fR
upon failure.
.PP
\fBestats_snapshot_alloc_from_log\fR returns \fIestats_snapshot\fR, or NULL
upon failure.
.SH SEE ALSO
.BR libestats (3)
